home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / prog / rexxpc_2.zip / REXXPC-2.DOC < prev    next >
Text File  |  1988-03-16  |  70KB  |  1,772 lines
  1. EXPRESSIONS
  2.  
  3.  
  4.  
  5. An expression is a sequence of terms and operators which is evaluated to
  6. give a final result.  The expression is evaluated left to right, except
  7. as modified by operator precedence (see the next section).
  8.  
  9.  
  10. TERMS
  11.  
  12.  
  13. Terms are the sub-components of an expression.   They fall into five
  14. classes.
  15.  
  16. A term may be a...    In which case its value is...
  17.  
  18. parenthesized expression
  19.                       the string resulting from evaluating that ex-
  20.                       pression
  21.  
  22. constant              the string constant itself
  23.  
  24. word (the name of a variable)
  25.                       the string currently assigned to that variable
  26.  
  27. word (not the name of a variable)
  28.                       the literal word itself
  29.  
  30. word followed by left paren (function)
  31.                       the string returned by the function
  32.  
  33.  
  34.  
  35. OPERATORS
  36.  
  37.  
  38.  
  39. Arithmetic operators
  40.  
  41.  
  42. REXXPC88 provides the usual arithmetic operators for addition, sub-
  43. traction, multiplication, division, and remainder.  The operators are:
  44.  
  45. +     returns a string representing the sum of its left and right oper-
  46.       ands.
  47.  
  48. -     returns a string representing the difference of its left and right
  49.       operands.
  50.  
  51. *     returns a string representing the product of its left and right
  52.       operands.
  53.  
  54. %     returns a string representing the integer portion of the  quotient
  55.       of its left and right operands.
  56.  
  57. //    returns a string representing the integer remainder when the left
  58.       operand is divided by the right operand.
  59.  
  60. /     returns a string representing the result when the left operand is
  61.       divided by the right operand.
  62.  
  63. **    returns a string representing the result when the left operand is
  64.       raised to the right operand whole power.
  65.  
  66.  
  67.  
  68. Comparison operators
  69.  
  70.  
  71. REXXPC88 provides thirteen operators for comparing strings.   The first
  72. six compare their operands character by character.  The others ignore
  73. leading blanks and pad the shorter operand with trailing blanks before
  74.  
  75.  
  76.  
  77. Expressions                                                            27
  78. the comparison.  Most of these operators also allow the not symbol in
  79. front of them to mean the opposite.
  80.  
  81. ==    returns "1" if left and right operands match character for character
  82.       and "0" otherwise.
  83.  
  84. /==   returns "0" if left and right operands match character for character
  85.       and "1" otherwise.
  86.  
  87. <<    strictly less than.  This operator will not pad either string.
  88.  
  89. >>    strictly greater than.  This operator will not pad either string.
  90.  
  91. <<=   strictly less than or equal to.  This operator will not pad either
  92.       string.
  93.  
  94. >>=   strictly greater than or equal to. This operator will not pad either
  95.       string.
  96.  
  97. =     returns "1" if operands match and "0" otherwise.
  98.  
  99. <> or >< returns "0" if operands match and "1" otherwise.
  100.  
  101. <     returns "1" if left operand is less than right operand and "0"
  102.       otherwise.  If both of the operands represent numbers, they are
  103.       compared as signed integers.  Otherwise they are compared alpha-
  104.       betically as character strings.
  105.  
  106. <=    returns "1" if left operand is less than or equal to the right op-
  107.       erand and "0" otherwise.  If both of the the operands represent
  108.       numbers, they are compared as signed integers.  Otherwise they are
  109.       compared alphabetically as character strings.
  110.  
  111. >     returns "1" if left operand is greater than right operand and "0"
  112.       otherwise.  If both of the the operands represent numbers, they are
  113.       compared as signed integers.  Otherwise they are compared alpha-
  114.       betically as character strings.
  115.  
  116. >=    returns "1" if left operand is greater than or equal to the right
  117.       operand and "0" otherwise.  If both of the operands represent num-
  118.       bers, they are compared as signed integers.  Otherwise they are
  119.       compared alphabetically as character strings.
  120.  
  121.  
  122.  
  123.  
  124. Logical operators
  125.  
  126.  
  127. REXXPC88 provides four operators for performing logical arithmetic.
  128.  
  129. │     returns 1 if either operand is 1 and 0 otherwise (logical or)
  130.  
  131. &     returns 1 if both operands are 1 and 0 otherwise (logical and).
  132.  
  133. \ or ¬ performs the NOT operation on the expression following this op-
  134.       erator.  The expression must evaluate to 0 or 1.  NOT will transform
  135.       0 to 1 and 1 to 0.
  136.  
  137.       Note: This character is actually a backslash (from upper left to
  138.       lower right).  Some printers do not have this character in its print
  139.       chain so the actual character seen in this description may vary.
  140.  
  141. &&    xor.  returns 0 if both operand expressions are either 1 or 0 (the
  142.       same) or 1 otherwise.
  143.  
  144. If the operands are neither 0 nor 1 an error message is generated.
  145.  
  146.  
  147. String operators
  148.  
  149.  
  150. REXXPC88 treats string expressions rather differently than most other
  151. languages.  Whitespace (a sequence or one or more adjacent blanks and/or
  152.  
  153.  
  154. Expressions                                                            28
  155. tabs between two terms) is treated as a concatenate-with-a-blank-in-
  156. between operator.  Abuttal (the absence of whitespace between two terms)
  157. is treated as a concatenate operator.
  158.  
  159. abuttal   returns the left term concatenated to the right term.
  160. whitespace returns the left term concatenated to the right term with a
  161.   single blank in between.
  162. ││        returns the left term concatenated to the right term (same as
  163.        abuttal).
  164.  
  165.  
  166.  
  167. OPERATOR PRECEDENCE
  168.  
  169.  
  170. Terms appearing between operators of higher precedence are evaluated be-
  171. fore terms appearing between operators of lower precedence, according to
  172. the usual rules of algebra (multiply and divide first, then add and sub-
  173. tract).  The operator precedence for REXXPC88 is as follows, listed
  174. highest precedence first:
  175.  
  176.   1.  -    +   \ or ¬  (unary minus, plus, not)
  177.   2.  **          (power)
  178.   3.  *    /   %   // (multiply, divide, integer divide, remainder)
  179.   4.  +    -      (add, subtract)
  180.   5.  " "         (concatenation with a blank)
  181.       ││          (concatenation without a blank)
  182.   6.  ==   /==    (exactly equal/not exactly equal)
  183.       <<   <<=    (exactly less than/exactly less than or equal to)
  184.       >>   >>=    (exactly greater than/exactly greater than or equal to)
  185.       =    <> ><  (equal/not equal)
  186.       <    >=     (less than/not less than)
  187.       >    <=     (greater than/not greater than)
  188.   7.  &           (and)
  189.   8.  │ or &&     (or and xor)
  190.  
  191.  
  192. NOTES
  193.  
  194.  
  195. 1.  The following instructions...
  196.  
  197.       say This is          an ││ expression
  198.       say The result is   ( 10 * 10 )0
  199.       result = 'answer'
  200.       say the result is   ( 10 * 10 )0
  201.       say The 'result' is ( 10 * 10 )0
  202.  
  203.     would produce on the screen...
  204.  
  205.       This is anexpression
  206.       The result is 1000
  207.       The answer is 1000
  208.       The result is 1000
  209.  
  210.     Observations:
  211.     a.  Note the use of "││" in the first example to force the abuttal of
  212.         "an" and "expression".
  213.     b.  The second example illustrates that numerical and non-numerical
  214.         strings can be intermixed in the same expression.
  215.     c.  The remaining examples show the behavior of initialized vs. un-
  216.         initialized variables.
  217.  
  218. 2.  In order for a function call to be recognized as such, the opening
  219.     parenthesis must immediately follow the function name, with no in-
  220.     tervening blank.  For example:
  221.  
  222.       say 'Length is' length('abc')
  223.  
  224.     calls the function length with the argument "abc", but
  225.  
  226.       say 'Length is' length ('abc')
  227.  
  228.     treats length as a variable name (or as a constant if there is no
  229.     variable by that name).
  230.  
  231. Expressions                                                           29
  232. COMPOUND VARIABLES
  233.  
  234.  
  235.  
  236.  
  237. A compound name is a variable name which contains subscripts.  It may
  238. appear anywhere a simple variable name would be valid (i.e. within an
  239. expression or as the target of an assignment).  The actual variable ref-
  240. erenced at run time is determined by replacing the subscripts with their
  241. current values to form the "actual name" of the variable.  The following
  242. example would print "one two three four":
  243.  
  244.   list.1 = 'one'
  245.  
  246.   list.2 = 'two'
  247.  
  248.   x = 3
  249.   list.x = 'three'
  250.  
  251.   x = 'mary'
  252.   list.x = 'four'
  253.  
  254.   say list.1 list.2 list.3 list.mary
  255.  
  256. Note that the value of a subscript need not be a number; it may be any
  257. string at all.  Thus compound variables allow you to implement arbitrary
  258. types of data collections (i.e., dictionaries, trees, etc.) in addition to
  259. simple arrays.
  260.  
  261. If a subscript name is currently undefined as a variable, then its value
  262. is the subscript taken as a literal.  Thus the following example will
  263. print "list.i list.j list.k" followed by "one two three":
  264.  
  265.   list.1 = 'one'
  266.   list.2 = 'two'
  267.   list.3 = 'three'
  268.  
  269.   say list.i list.j list.k
  270.  
  271.   i = 1; j = 2; k = 3
  272.  
  273.   say list.i list.j list.k
  274.  
  275. An entire collection may be initialized by assigning a value to the stem
  276. of the collection.  Thus
  277.  
  278.   animals. = 'I don''t know that one'
  279.   animals.pig = 'oink oink'
  280.   animals.hen = 'cackel'
  281.   animals.rooster = 'cockadoodledoo'
  282.  
  283.   say 'Name an animal'
  284.   choice = ask()
  285.   say animals.choice
  286.  
  287. would respond "oink oink" to "pig" but "I don't know that one" to
  288. "sparrow".
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308. Compound variables                                                     31
  309. PROCEDURES AND FUNCTIONS
  310.  
  311.  
  312.  
  313. A procedure or function is block of code whose purpose is to accept a list
  314. of arguments and perform some operation using them.  We'll refer to pro-
  315. cedures and functions collectively as routines.  The inner workings of
  316. routines are generally kept hidden from the rest of the program and serve
  317. as "black boxes" to perform useful operations.
  318.  
  319. REXXPC88 procedures differ from functions only in the syntax used to in-
  320. voke them and in the fact that functions must return a value whereas
  321. procedures needn't.  If desired, the same routine can be called as a
  322. procedure at one time and as a function at some other time.1
  323.  
  324. A routine may be one of three types:
  325.  
  326. ∙   internal routine
  327. ∙   built-in routine
  328. ∙   external routine
  329.  
  330. The first is a labelled entry point you've defined in your program.  The
  331. second is a routine that REXXPC88 provides as part of its internal li-
  332. brary.  The third is an external REXXPC88 program whose name is the name
  333. of the function and whose filetype is ".BAT".  The calling conventions are
  334. exactly the same for each type of routine.
  335.  
  336.  
  337.  
  338. ARGUMENT PASSING AND NAME HIDING
  339.  
  340.  
  341. ∙   A routine may be called with or without arguments.  The same routine
  342.     may be called with different numbers of arguments at different times.
  343.     If a function is called with zero arguments, the parentheses are still
  344.     required.
  345. ∙   The number of arguments passed to a routine, as well as their values,
  346.     are available thru the arg() built-in routine.
  347. ∙   If a procedure instruction is encountered in the body of a routine
  348.     then a new symbol table is created at that point.  All references to
  349.     variables from that point on will be satisfied from the new symbol
  350.     table.  Variables defined prior to the procedure instruction become
  351.     undefined until a return instruction is executed, at which point the
  352.     current symbol table is discarded and the preceding symbol table is
  353.     re-established.
  354. ∙   If a procedure expose instruction is used, then a new symbol table is
  355.     still created but in addition some variables in the caller's symbol
  356.     table are shared (see the procedure expose instruction).
  357. ∙   If no procedure instruction is encountered in a routine, then the
  358.     symbol table established by the caller continues to be used.2
  359.  
  360.  
  361. RETURN VALUES
  362.  
  363.  
  364. The value returned by a routine is handled differently depending on
  365. whether the routine was called as a function or as a subroutine.
  366.  
  367. 1.  For a routine called as a subroutine: If the variable returns a value,
  368.     that value is stored in the special variable named "result".  Other-
  369.     wise the current value of "result" (if any) is dropped.
  370.  
  371.  
  372.  
  373.  
  374.  
  375. 1   A procedure is generally called for its side effects.  A function is
  376.     generally called for its value and is not supposed to produce side
  377.     effects (although no such restriction is imposed by the REXX lan-
  378.     guage).
  379.  
  380. 2   Note that there is no way to access "global" variables unless they
  381.     are passed explicitly from one routine to the next either as arguments
  382.     or as exposed variables.
  383.  
  384.  
  385. Procedures and Functions                                               32
  386. 2.  For a routine called as a function:  If the function returns a value,
  387.     that value is substituted into the expression at the position where
  388.     the function was called.  Otherwise REXXPC88 stops with an error
  389.     message.
  390.  
  391.  
  392.  
  393. BUILT-IN ROUTINES
  394.  
  395.  
  396.  
  397. General purpose routines
  398.  
  399.  
  400.  
  401. ┌────────────────────────────────────────────────────────────────────────┐
  402. │               ABBREV( information , info [ ,length ] )                 │
  403. └────────────────────────────────────────────────────────────────────────┘
  404.  
  405. returns 1 if info is equal to the leading characters of information and
  406. info is not less than the minimum length, length.  Returns 0 if either of
  407. these conditions is not met.  The minimum length may be specified as the
  408. third argument; the default is the length of info.
  409.  
  410.   Examples:
  411.  
  412.   ABBREV('Print','Pri')    == 1
  413.   ABBREV('PRINT','Pri')    == 0
  414.   ABBREV('PRINT','PRI',4)  == 0
  415.   ABBREV('PRINT','PRY')    == 0
  416.   ABBREV('PRINT','')       == 1
  417.   ABBREV('PRINT','',1)     == 0
  418.  
  419. Note:  A null string will always match is a length of 0 (or the default)
  420. is used.  This allows a default keyword to be selected automatically if
  421. desired.
  422.  
  423. ┌────────────────────────────────────────────────────────────────────────┐
  424. │                             ABS( number )                              │
  425. └────────────────────────────────────────────────────────────────────────┘
  426.  
  427. returns the absolute value of number.  The result has no sign and is for-
  428. matted according to the current NUMERIC settings.
  429.  
  430.   Examples:
  431.  
  432.   ABS('12.3')      == 12.3
  433.   ABS(' -0.307')   == 0.307
  434.  
  435. ┌────────────────────────────────────────────────────────────────────────┐
  436. │                               ADDRESS()                                │
  437. └────────────────────────────────────────────────────────────────────────┘
  438.  
  439. returns the name of the environment to which host commands are currently
  440. being submitted.
  441.  
  442. ┌────────────────────────────────────────────────────────────────────────┐
  443. │                     ARG( [ argn0 [ ,option ] ] )                       │
  444. └────────────────────────────────────────────────────────────────────────┘
  445.  
  446. returns an argument string, or information about the argument strings to
  447. a program or internal routine.
  448.  
  449. If no parameter is given, the number of arguments strings passed to the
  450. program or internal routine is returned.
  451.  
  452. If only n is specified, n-th argument is returned.  If the argument string
  453. does not exist, the null string is returned.  n must be positive.
  454.  
  455. If option is specified, the function tests for the existence of the nth
  456. argument string.  Possible values for option (of which only the first
  457. character is significant) are:
  458.  
  459.  
  460.  
  461.  
  462. Procedures and Functions                                               33
  463. E        (Exists); returns 1 if the nth argument exists; that is, if it
  464.          was explicitly specified when the routine was invoked.  Returns
  465.          0 otherwise.
  466. O        (Omitted); returns 1 if the nth argument was omitted; that is,
  467.          if it was not explicitly specified when the routine was invoked.
  468.          Returns 0 otherwise.
  469.  
  470. If no routine is currently active, the argument list is that with which
  471. the program was invoked (i.e. the command line).  The program fragment
  472.  
  473.   x = 'one'
  474.   y = 'two three'
  475.   say foo(x, y)
  476.   return
  477.  
  478.   foo:
  479.   say 'Foo received' arg() 'arguments'
  480.   return arg(1) arg(2)
  481.  
  482. would display the lines:
  483.  
  484.   Foo received 2 arguments
  485.   one two three
  486.  
  487. ┌────────────────────────────────────────────────────────────────────────┐
  488. │      CENTER( string, k [ ,pad ] ) / CENTRE( string, k [ ,pad ] )       │
  489. └────────────────────────────────────────────────────────────────────────┘
  490.  
  491. Returns a string of length k with string centered in it, with pad char-
  492. acters (the default pad character is a blank) added as necessary to make
  493. up the length.  If the string is longer than k, then it will be truncated
  494. at both ends to fit.  If an odd number of characters are truncated or
  495. added, then the right hand end loses or gains one more character than the
  496. left hand end.
  497.  
  498.   Examples:
  499.  
  500.   CENTRE(abc,7)            == '  ABC  '
  501.   CENTRE(ABC,8,'-')        == '--ABC---'
  502.   CENTER('The true REX',8) == 'e true R'
  503.   CENTER('The true REX',7) == 'e true '
  504.  
  505.  
  506.   Note:  This function may be called either CENTER or CENTRE,
  507.   which avoids errors due to the difference between the
  508.   British and American spellings.
  509.  
  510. ┌────────────────────────────────────────────────────────────────────────┐
  511. │                COMPARE( string1 , string2 [ , pad ] )                  │
  512. └────────────────────────────────────────────────────────────────────────┘
  513.  
  514. returns 0 if string1 and string2 are identical.  If they are not, the re-
  515. turned number is positive and is the position of the first character that
  516. is not the same in both strings. The shorter string is padded on the right
  517. with pad if necessary.  The default pad character is a blank.
  518.  
  519.   Examples:
  520.  
  521.   COMPARE('abc','abc')      == 0
  522.   COMPARE('abc','ak')       == 2
  523.   COMPARE('ab ','ab')       == 0
  524.   COMPARE('ab ','ab',' ')   == 0
  525.   COMPARE('ab ','ab','x')   == 3
  526.   COMPARE('ab-- ','ab','-') == 5
  527.  
  528. ┌────────────────────────────────────────────────────────────────────────┐
  529. │                          COPIES( string, n )                           │
  530. └────────────────────────────────────────────────────────────────────────┘
  531.  
  532. Returns n concatenated copies of string.  n must be positive or 0.
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539. Procedures and Functions                                               34
  540.   Examples:
  541.  
  542.   COPIES('abc',3) == 'abcabcabc'
  543.   COPIES('abc',0) == ''
  544.  
  545.  
  546. ┌────────────────────────────────────────────────────────────────────────┐
  547. │                     DATATYPE( string [ ,type ] )                       │
  548. └────────────────────────────────────────────────────────────────────────┘
  549.  
  550. If only string is specified, the returned result is 'NUM' if string is a
  551. valid REXXPC88 number, or 'CHAR' otherwise.
  552.  
  553. If type is specified, the returned result is 1 if string matches the type,
  554. or 0 otherwise. If string is null, 0 is returned (except when type is "X",
  555. which returns 1 for a null string).  The valid types (of which only the
  556. first character is significant) are:
  557.  
  558. A         (Alphanumeric); returns 1 if string only contains characters
  559.           from the ranges "a-z", "A-Z", and "0-9".
  560. B         (Bits); returns 1 if string only contains the characters "0"
  561.           and/or "1".
  562. L         (Lower case); returns 1 if string only contains characters from
  563.           the range "a-z".
  564. M         (Mixed case); returns 1 if string contains characters from the
  565.           ranges "a-z" and "A-Z".
  566. N         (Number); returns 1 if string is a valid REXXPC88 number.
  567. S         (Symbol); returns 1 if string only contains characters that are
  568.           valid in REXXPC88 symbols. Note that lower case alphabetics are
  569.           permitted.
  570. U         (Upper case); returns 1 if string only contains characters from
  571.           the range "A-Z".
  572. W         (Whole number); returns 1 if string is a REXXPC88 whole number.
  573. X         (heXidecimal); returns 1 if string only contains characters
  574.           from the ranges "a-f", "A-F", "0-9" and blank (so long as blanks
  575.           only appear between pairs of hexidecimal characters, as usual).
  576.           Also returns 1 if string is a null string, which is a valid
  577.           hexidecimal string.
  578.  
  579. ┌────────────────────────────────────────────────────────────────────────┐
  580. │                          DATE( [ option ] )                            │
  581. └────────────────────────────────────────────────────────────────────────┘
  582.  
  583. Returns the local date in the format: dd Mmm yyy. e.g. '27 Aug 1982', with
  584. no leading zero on the day.  The following formats (first letter signif-
  585. icant) may be supplied to obtain alternative formats:
  586.  
  587. Century   Returns the number of days so far in this century in the
  588.           format: ddddd (no leading zeros).
  589.  
  590.           Note: not supported.
  591. Days      Returns the number of days so far in this year in the format:
  592.           ddd (no leading zeros).
  593. European  Returns the date in the format: dd/mm/yy.
  594. Julian-OS Returns the date in "OS" format: yyddd.
  595. Month     Returns full name of the current month, e.g. 'August'.
  596. Normal    Returns the date in the default format as specified above.
  597. Ordered   Returns date in the format: yy/mm/dd (suitable for sorting,
  598.           etc.).
  599. Sorted    Returns date in the format: yyyymmdd (suitable for sorting,
  600.           etc.).
  601. USA       Returns date in the format: mm/dd/yy.
  602. Weekday   Returns day of week, e.g. 'Tuesday'.
  603.  
  604. Note: The first call to DATE in one expression causes a time stamp to be
  605. made which is then used for all calls to this function in that expression.
  606. Hence if multiple calls to any of the DATE functions are made in a single
  607. expression, they are guaranteed to be consistent with each other.
  608.  
  609. ┌────────────────────────────────────────────────────────────────────────┐
  610. │                   DELSTR( string , n [ ,length ] )                     │
  611. └────────────────────────────────────────────────────────────────────────┘
  612.  
  613.  
  614.  
  615.  
  616. Procedures and Functions                                               35
  617. deletes the sub-string of string that begins at the nth character,  and
  618. is of length length.  If length is not specified, the rest of the string
  619. is deleted (including the nth character).  length must be non-negative,
  620. and n must be positive.  If n is greater than the length of string, the
  621. string is returned unchanged.
  622.  
  623.   Examples:
  624.  
  625.   DELSTR('abcd',3)    == 'ab'
  626.   DELSTR('abcde',3,2) == 'abe'
  627.   DELSTR('abcde',6)   == 'abcde'
  628.  
  629. ┌────────────────────────────────────────────────────────────────────────┐
  630. │                   DELWORD( string , n [ ,length ] )                    │
  631. └────────────────────────────────────────────────────────────────────────┘
  632.  
  633. deletes the sub-string of string that begins at the nth word,  and is of
  634. length length blank-delimited words.  If length is omitted it defaults to
  635. be the remaining words in the string (including the nth word). length must
  636. be non-negative, and n must be positive.  If n is greater than the number
  637. of words in string, the string is returned unchanged.  The string deleted
  638. includes any blanks following the final word involved, but none of the
  639. blanks preceding the first word involved.
  640.  
  641.   Examples:
  642.  
  643.   DELWORD('Now is the  time',2,2) == 'Now time'
  644.   DELWORD('Now is the time',3)    == 'Now is '
  645.   DELWORD('Now is  time',5)       == 'Now is  time'
  646.  
  647. ┌────────────────────────────────────────────────────────────────────────┐
  648. │                               DIGITS()                                 │
  649. └────────────────────────────────────────────────────────────────────────┘
  650.  
  651. returns the current setting of NUMERIC DIGITS. See the NUMERIC instruction
  652. for more information.
  653.  
  654.   Example:
  655.  
  656.   DIGITS()  == 9  /* if default */
  657.  
  658. ┌────────────────────────────────────────────────────────────────────────┐
  659. │                                FORM()                                  │
  660. └────────────────────────────────────────────────────────────────────────┘
  661.  
  662. returns the current setting of NUMERIC FORM. See the NUMERIC instruction
  663. for more information.
  664.  
  665.   Example:
  666.  
  667.   FORM()  == 'SCIENTIFIC'  /* if default */
  668.  
  669. ┌────────────────────────────────────────────────────────────────────────┐
  670. │           FORMAT( number [ , [ before ] [ , [ after ] ] ] )            │
  671. └────────────────────────────────────────────────────────────────────────┘
  672.  
  673. rounds and formats number.
  674.  
  675. If only number is given, it will be rounded and formatted to standard
  676. REXXPC88 rules, just as though the operation "number+0" had been carried
  677. out.  The arguments before and after describe how many characters are to
  678. be used for the integer and decimal parts of the result respectively.  If
  679. either of these is omitted, the number of characters used will be as many
  680. as are needed for that part.
  681.  
  682. If before is not large enough to contain the integer part of the number,
  683. an error results.  If after is not the same size as the decimal part of
  684. the number, the number will be rounded (or extended with zeros) to fit.
  685. Specifying 0 will cause the number to be rounded to an integer (that is,
  686. it will have no decimal part).
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693. Procedures and Functions                                               36
  694.   Examples:
  695.  
  696.   FORMAT('3',4)            == '   3'
  697.   FORMAT('1.73'4,0)        == '   2'
  698.   FORMAT('1.73',4,3)       == '   1.730'
  699.   FORMAT('-.76',4,1)       == '  -0.8'
  700.   FORMAT('3.03',4)         == '   3.03'
  701.   FORMAT(' - 12.73',,4)    == '-12.7300'
  702.   FORMAT(' - 12.73')       == '-12.73'
  703.   FORMAT('0.000')          == '0'
  704.  
  705. A further two arguments may be passed to the FORMAT function to control
  706. the use of exponential notation.  The full syntax of the function is
  707. therefore:
  708.  
  709. ┌────────────────────────────────────────────────────────────────────────┐
  710. │ FORMAT( number [ , [ before ] [ , [ after ] [ , [ expp ] [ , expt ]    │
  711. │                                ] ] )                                   │
  712. └────────────────────────────────────────────────────────────────────────┘
  713.  
  714. The first three arguments are as described above, and in addition expp
  715. and expt control the exponent part of the result, which by default is
  716. formatted according to the current NUMERIC settings of DIGIT and FORM.
  717. expp sets the number of places (digits) to be used for the exponent part,
  718. the default being to use as many as needed.  expt sets the trigger point
  719. for use of exponential notation.  If the number of places needed for the
  720. integer or decimal part exceeds expt or twice expt respectively, expo-
  721. nential notation will be used.  The default is the current setting of NU-
  722. MERIC DIGITS.  If 0 is specified for expt, exponential notation is always
  723. used unless the exponent would be zero.
  724.  
  725. If 0 is specified for the expp field, no exponent will be supplied, and
  726. the number will be expressed in "simple" form with added zeros as neces-
  727. sary (this overrides a 0 value of expt if necessary).  Otherwise, if expp
  728. is not large enough to contain the exponent, an error results.  If the
  729. exponent will be 0 in this case (a non-zero expp), then expp+2 blanks are
  730. supplied for the exponent part of the result.
  731.  
  732.   Examples:
  733.  
  734.   FORMAT('12345.73',,,2,2)  ==  '1.234573E+04'
  735.   FORMAT('12345.73',,3,,0)  ==  '1.235E+4'
  736.   FORMAT('1.234573',,3,,0)  ==  '1.235'
  737.   FORMAT('123.45',,3,2,0)   ==  '1.235E+02'
  738.   FORMAT('1.2345',,3,2,0)   ==  '1.235'
  739.   FORMAT('12345.73',,,3,6)  ==  '12345.73'
  740.   FORMAT('1234567e5',,3,0)  ==  '123456700000.000'
  741.  
  742. Note:  If NUMERIC FORM ENGINEERING is in effect, up to three digits may be
  743. needed for the integer part of the result (before).
  744.  
  745. ┌────────────────────────────────────────────────────────────────────────┐
  746. │                                FUZZ()                                  │
  747. └────────────────────────────────────────────────────────────────────────┘
  748.  
  749. returns the current setting of NUMERIC FUZZ.  See the NUMERIC instruction
  750. for more information.
  751.  
  752.   Example:
  753.  
  754.   FUZZ()  == 0  /* if default */
  755.  
  756. ┌────────────────────────────────────────────────────────────────────────┐
  757. │     INSERT( new , target [ , [ n ] [ , [ length ] [ , pad ] ] ] )      │
  758. └────────────────────────────────────────────────────────────────────────┘
  759.  
  760. inserts the string new, padded to the length length, into the string target
  761. after the nth character.  length and n must be non-negative.  If n is
  762. greater than the length of the target string, padding is added before the
  763. new string also.  The default value fr n is 0, which means insert before
  764. the beginning of the string.  The default value for length is the length
  765. of new.  The default pad character is a blank.
  766.  
  767.  
  768.  
  769.  
  770. Procedures and Functions                                               37
  771.   Examples:
  772.  
  773.   INSERT(' ','abcdef',3)         ==  'abc def'
  774.   INSERT('123','abc',5,6)        ==  'abc  123   '
  775.   INSERT('123','abc',5,6,'+')    ==  'abc++123+++'
  776.   INSERT('123','abc')            ==  '123abc'
  777.   INSERT('123','abc',5,,'-')     ==  '123--abc'
  778.  
  779. ┌────────────────────────────────────────────────────────────────────────┐
  780. │               LASTPOS( needle , haystack [ , start ] )                 │
  781. └────────────────────────────────────────────────────────────────────────┘
  782.  
  783. Returns the position of the last occurrence of one string in another. (see
  784. also POS).  If the string needle is not found, then '0' is returned.  By
  785. default the search starts at the last character of haystack (i.e.,
  786. start=LENGTH(string)) and scans backwards.  This may be overridden by
  787. specifying start, the point at which to start the backwards scan.  start
  788. must be a positive whole number.
  789.  
  790.   Examples:
  791.  
  792.   LASTPOS(' ','abc def ghi')    == 8
  793.   LASTPOS(' ','abcdefghi')      == 0
  794.   LASTPOS(' ','abc def ghi',7)  == 4
  795.  
  796. ┌────────────────────────────────────────────────────────────────────────┐
  797. │                     LEFT( string , k [ , pad ] )                       │
  798. └────────────────────────────────────────────────────────────────────────┘
  799.  
  800. Returns a string of length k containing the left-most k characters of
  801. string that is padded with pad characters (or truncated) on the right as
  802. needed.  The default pad character is a blank.  k must be non-negative.
  803. Exactly equivalent to SUBSTR(string,l,k,[,pad]).
  804.  
  805.   Examples:
  806.  
  807.   LEFT('abc d',8)     == 'abc d   '
  808.   LEFT('abc d',8,'.') == 'abc d...'
  809.   LEFT('abc  def',7)  == 'abc  de'
  810.  
  811. ┌────────────────────────────────────────────────────────────────────────┐
  812. │                           LENGTH( string )                             │
  813. └────────────────────────────────────────────────────────────────────────┘
  814.  
  815. Length returns the length of the string expression passed as an argument.
  816. For example, the following expressions all evaluate to "7":
  817.  
  818.   LENGTH('abc def')
  819.   4 + LENGTH(123)
  820.   7 + LENGTH('')
  821.  
  822. ┌────────────────────────────────────────────────────────────────────────┐
  823. │             LINEIN( [ name ] [ , [ line ] [ , count ] ] )              │
  824. └────────────────────────────────────────────────────────────────────────┘
  825.  
  826. Returns count (0 or 1) lines read from the character input stream name.
  827. The default count is 1.  The form of name is implementation-dependent.  If
  828. name is omitted, then the line will be read from the default input stream.
  829.  
  830. For PC/DOS the standard input stream is the keyboard if no name is given
  831. or name is "KEYBOARD".  If no line is available from the keyboard (using
  832. DOS function x'0a'), the program will wait until enter is pressed. A "?"
  833. prompt will be displayed for this option to indicate console read active.
  834.  
  835. If name is "EXQUE" the next line (if any) from the external interrupt
  836. queue is returned.  If no line exists in the external interrupt queue, the
  837. null string is returned.
  838.  
  839. For this release the line and count options are not supported. Also LINEIN
  840. does not support files at this time.  Use the READ function instead.
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847. Procedures and Functions                                               38
  848. ┌────────────────────────────────────────────────────────────────────────┐
  849. │            LINEOUT( [ name ] [ , [ string ] [ , line ] ] )             │
  850. └────────────────────────────────────────────────────────────────────────┘
  851.  
  852. LINEOUT is not supported at this time.  Use the WRITE function instead.
  853.  
  854. ┌────────────────────────────────────────────────────────────────────────┐
  855. │                           LINES( [ name ] )                            │
  856. └────────────────────────────────────────────────────────────────────────┘
  857.  
  858. returns the number of complete lines remaining in the character input
  859. stream name. If the stream has already been read with the CHARIN function,
  860. this may include an initial partial line.  In the case of persistent
  861. streams (files) the count starts at the current read position.
  862.  
  863. The form of name is implementation-dependent.  If name is omitted, then
  864. the number of complete lines available in the default input stream is
  865. returned.
  866.  
  867. If an implementation cannot determine the count accurately or effi-
  868. ciently, then it may return 1 for any non-zero result.  An actual line
  869. count may therefore be used only in programs specific to a particular
  870. environment in which LINES is fully supported.
  871.  
  872. For PC/DOS only two names are supported: "KEYBOARD" and "EXQUE".  If name
  873. is not supplied, the count of lines remaining in the "KEYBOARD" will be
  874. returned.  As no accurate count can be established, '1' is returned if any
  875. keystrokes are detected via the INT 16h status call (AH=1).
  876.  
  877. "EXQUE" refers to the count of lines queued in the external interrupt
  878. queue.  This queue will only contain lines if the queue interface to the
  879. resident REXXPC88 version specified the external queue as the destination
  880. for the message.
  881.  
  882. ┌────────────────────────────────────────────────────────────────────────┐
  883. │                     MAX( number , [ number ]...)                       │
  884. └────────────────────────────────────────────────────────────────────────┘
  885.  
  886. returns the largest number from the given list of numbers - that is, the
  887. number in the list which can be derived by adding a positive number or
  888. zero to any of the other numbers in the list.  The result is formatted
  889. according to the current NUMERIC settings.
  890.  
  891.   Examples:
  892.  
  893.   MAX(12,6,7,9)         ==   12
  894.   MAX(17.3,3,19,17.03)  ==   19
  895.   MAX(-7,-3,-4.3)       ==   -3
  896.  
  897. ┌────────────────────────────────────────────────────────────────────────┐
  898. │                     MIN( number , [ number ]...)                       │
  899. └────────────────────────────────────────────────────────────────────────┘
  900.  
  901. returns the smallest number from the given list of numbers - that is, the
  902. number in the list which can be derived by subtracting a positive number
  903. or zero from any of the other numbers in the list.  The result is for-
  904. matted according to the current NUMERIC settings.
  905.  
  906.   Examples:
  907.  
  908.   MIN(12,6,7,9)      ==    6
  909.   MIN(17.3,19,17.03) ==   17.03
  910.   MIN(-7,-3,-4.3)    ==   -7
  911.  
  912. ┌────────────────────────────────────────────────────────────────────────┐
  913. │      OVERLAY( new , target [ , [ n ] [ length ] [ , pad ] ] ] )        │
  914. └────────────────────────────────────────────────────────────────────────┘
  915.  
  916. overlays the string new, padded or truncated to length length, onto the
  917. string target starting at the nth character.  If length is specified it
  918. must be positive or zero.  If n is greater than the length of the target
  919. string, padding is added before the new string also.  The default pad
  920. character is a blank, and the default value for n is 1.  n must be greater
  921. than 0.  The default value for length is the length of new.
  922.  
  923.  
  924. Procedures and Functions                                               39
  925.   Examples:
  926.  
  927.   OVERLAY(' ','abcdef',3)      == 'ab def'
  928.   OVERLAY('.','abcdef',3,2)    == 'ab. ef'
  929.   OVERLAY('qq','abcd')         == 'qqcd'
  930.   OVERLAY('qq',abcd',4)        == 'abcqq'
  931.   OVERLAY('123','abc',5,6,'+') == 'abc+123+++'
  932.  
  933. ┌────────────────────────────────────────────────────────────────────────┐
  934. │                 POS( needle , haystack [ , start ] )                   │
  935. └────────────────────────────────────────────────────────────────────────┘
  936.  
  937. Returns the position of the one string in another.  See also the LASTPOS
  938. function.  If the string needle is not found, then '0' is returned.  By
  939. default the search starts at the first character of haystack (i.e.,
  940. start=1).  This may be overridden by specifying start (which must be a
  941. positive whole number), the point at which to start the search.
  942.  
  943.   Examples:
  944.  
  945.   POS(' ','abc def ghi')   == 4
  946.   POS('x','abc def ghi')   == 0
  947.   POS(' ','abc def ghi',5) == 8
  948.  
  949.  
  950. ┌────────────────────────────────────────────────────────────────────────┐
  951. │                               QUEUED()                                 │
  952. └────────────────────────────────────────────────────────────────────────┘
  953.  
  954. Returns the number of lines remaining in the data queue at the time when
  955. the function is invoked. If QUEUED()=0 then a PULL or PARSE PULL will read
  956. from the console input buffer.  If there is no user input waiting the will
  957. cause a console read ("?").
  958.  
  959.   Example:
  960.  
  961.   QUEUED()  == '5' /* parhaps */
  962.  
  963. ┌────────────────────────────────────────────────────────────────────────┐
  964. │              RANDOM( [ min ] [ , [ max ] ] [ , seed ] )                │
  965. └────────────────────────────────────────────────────────────────────────┘
  966.  
  967. returns a quasi-random non-negative whole number in the range min to max
  968. inclusive.  If only one argument is specified, the range will be from 0
  969. to that number.  Otherwise the default values for min and max are 0 and
  970. 999 respectively.  A specific seed (which must be a whole number) for the
  971. random number may be specified as the third argument to start a repeatable
  972. sequence of results.
  973.  
  974. The magnitude of the range (that is, max minus min) may not exceed 100000.
  975.  
  976.   Examples:
  977.  
  978.   RANDOM()             ==   305    /* possible */
  979.   RANDOM(5,8)          ==   7      /* possible */
  980.   RANDOM(,,1985)       ==   663    /* possible but constant answer */
  981.   RANDOM(2)            ==   0      /* possible */
  982.  
  983. Notes:
  984.  
  985. 1.  To obtain a predictable sequence of quasi-random numbers, call RANDOM
  986.     a number of times, but only specify seed on the first call.  For ex-
  987.     ample, to simulate ten throws of a six sided dice:
  988.  
  989.       say random(1,6,12345)
  990.       do 9
  991.         say random(1,6)
  992.       end
  993.  
  994.     The numbers are generated mathematically, using the initial seed, so
  995.     that as far as possible they appear to be random.  Running the program
  996.     again will produce the same sequence; using a different initial seed
  997.     will almost always produce a difference sequence. If you do not provide
  998.  
  999.  
  1000.  
  1001. Procedures and Functions                                               40
  1002.     a seed, then the first time RANDOM is called an arbitrary seed will
  1003.     be used.  (The seed used will be the timer tick count from BIOS).
  1004. 2.  The random number generator is global for the entire program - the
  1005.     current seed is not saved across routine calls.
  1006. 3.  The actual implementation differs from VM and so will not produce
  1007.     indentical results in a ported VM REXX program.
  1008.  
  1009. ┌────────────────────────────────────────────────────────────────────────┐
  1010. │                           REVERSE( string )                            │
  1011. └────────────────────────────────────────────────────────────────────────┘
  1012.  
  1013. Returns string, swapped end for end.
  1014.  
  1015.     Example:
  1016.  
  1017.     reverse('ABc.') == '.cBA'
  1018.  
  1019.  
  1020. ┌────────────────────────────────────────────────────────────────────────┐
  1021. │                  RIGHT( string , k [ , pad ] )                         │
  1022. └────────────────────────────────────────────────────────────────────────┘
  1023.  
  1024. Returns a string of length k containing the right-most k characters of
  1025. string.  That is, padded with pad characters (or truncated) on the left
  1026. as needed.  The default pad character is a blank.  k must be non-negative.
  1027.  
  1028.     Example:
  1029.  
  1030.     RIGHT('abc  d',8)   == '  abc   d'
  1031.     RIGHT('abc def',5)  == 'c def'
  1032.     RIGHT('12',5,'0')   == '00012'
  1033.  
  1034.  
  1035. ┌────────────────────────────────────────────────────────────────────────┐
  1036. │                            SIGN( number )                              │
  1037. └────────────────────────────────────────────────────────────────────────┘
  1038.  
  1039. number is rounded according to the current setting of NUMERIC DIGITS.  If
  1040. the number is then less than 0 then '-1' is returned; if it is 0 then '0'
  1041. is returned; and if it is greater than 0 then '1' is returned.
  1042.  
  1043.     Examples:
  1044.  
  1045.     SIGN('12.3')    ==   1
  1046.     SIGN(0.0)       ==   0
  1047.     SIGN('-0.307')  ==  -1
  1048.  
  1049. ┌────────────────────────────────────────────────────────────────────────┐
  1050. │                 SPACE( string [ , [ n ] [ , pad ] ] )                  │
  1051. └────────────────────────────────────────────────────────────────────────┘
  1052.  
  1053. Formats the blank-delimited words in string with n pad characters between
  1054. each word. n must be non-negative. if n is 0, then all blanks are removed.
  1055. Leading and trailing blanks are always removed.  The default for n is 1,
  1056. and the default pad character is a blank.
  1057.  
  1058.     Examples:
  1059.  
  1060.     SPACE('abc  def  ')        == 'abc def'
  1061.     SPACE('  abc def',3)       == 'abc   def'
  1062.     SPACE('abc  def  ',1)      == 'abc def'
  1063.     SPACE('abc  def  ',0)      == 'abcdef'
  1064.     SPACE('abc  def  ',2,'+')  == 'abc++def'
  1065.  
  1066.  
  1067. ┌────────────────────────────────────────────────────────────────────────┐
  1068. │              STRIP( string [ , [ option ] [ , char ] ] )               │
  1069. └────────────────────────────────────────────────────────────────────────┘
  1070.  
  1071. Removes Leading, Trailing, or Both leading and trailing characters from
  1072. string when the first character of option is 'L', 'T', or 'B' respectively
  1073. (these may be given in upper or lower case). The default is 'B'. The third
  1074. argument, char specifies the character to be removed, with the default
  1075. being a blank.  If given, char must be exactly one character long.
  1076.  
  1077.  
  1078. Procedures and Functions                                               41
  1079.     Examples:
  1080.  
  1081.     STRIP('  ab c  ')      == 'ab c'
  1082.     STRIP('  ab c  ','L')  == 'ab c  '
  1083.     STRIP('  ab c  ','t')  == '  ab c'
  1084.     STRIP('12.7000',,'0')  == '12.7'
  1085.     STRIP('0012.700',,'0') == '12.7'
  1086.  
  1087.  
  1088. ┌────────────────────────────────────────────────────────────────────────┐
  1089. │             SUBSTR( string , pos [ , length [ , pad ] ] )              │
  1090. └────────────────────────────────────────────────────────────────────────┘
  1091.  
  1092. substr extracts a substring of specified length, starting at pos.  If
  1093. length would exceed the remainder of string then characters of value pad
  1094. are appended as required.  If length is omitted it defaults to the length
  1095. of the remaining string.  If pad is omitted it defaults to a blank.
  1096.  
  1097. For example, the following expressions all evaluate to "abc$$$":
  1098.  
  1099.     SUBSTR('abc$$$', 1)
  1100.     SUBSTR('xyzabc$$$', 4)
  1101.     SUBSTR('xyzabc', 4, 6, '$')
  1102.  
  1103.  
  1104. ┌────────────────────────────────────────────────────────────────────────┐
  1105. │                     SUBWORD( string , n [ , k ] )                      │
  1106. └────────────────────────────────────────────────────────────────────────┘
  1107.  
  1108. Returns the substring of string that starts at the nth word, and is of
  1109. length k blank-delimited words.  n must be positive.  If k is omitted it
  1110. defaults to the remaining words in the string.  The returned string will
  1111. never have leading or trailing blanks, but will include all blanks between
  1112. selected words.
  1113.  
  1114.     Example:
  1115.  
  1116.     SUBWORD('Now is the  time',2,2) == 'is the'
  1117.     SUBWORD('Now is the  time',3)   == 'the  time'
  1118.     SUBWORD('Now is the  time',5)   == ''
  1119.  
  1120.  
  1121. ┌────────────────────────────────────────────────────────────────────────┐
  1122. │                            SYMBOL( name )                              │
  1123. └────────────────────────────────────────────────────────────────────────┘
  1124.  
  1125. If name is not a valid REXXPC88 symbol, 'BAD' is returned.  If it is the
  1126. name of a variable (that is, a symbol that has been assigned a value),
  1127. 'VAR' is returned.  Otherwise 'LIT' is returned, which indicates that it
  1128. is either a constant symbol or a symbol that has not yet been assigned a
  1129. value (that is a Literal).
  1130.  
  1131. ┌────────────────────────────────────────────────────────────────────────┐
  1132. │                          TIME( [ option ] )                            │
  1133. └────────────────────────────────────────────────────────────────────────┘
  1134.  
  1135. by default returns the local time in the 24-hour clock format 'hh:mm:ss'
  1136. (hours, minutes, and seconds).  e.g.,  '04:41:37'.
  1137.  
  1138. The following options (first letter significant) may be supplied to obtain
  1139. alternative formats:
  1140.  
  1141. Civil     returns 'hh:mmxx', the time in Civil format, in which the hours
  1142.           may take values from 1 thru 12, and the minutes the values 00
  1143.           through 59. The minutes are immediately followed by the letters
  1144.           "am" or "pm" to distinguish times in the morning (midnight 12:00
  1145.           am through 11:59am) from noon and afternoon (noon 12:00pm
  1146.           through 11:59pm).  The hour will not have a leading zero.  The
  1147.           minute field shows the current minute (rather than the nearest
  1148.           minute) for consistency with other TIME results.
  1149. Normal    Returns the time in the default format described above.
  1150. Long      Returns time in the format:  hh:mm:ss.uuuuuu (uuuuuu is the
  1151.           fraction of seconds, in hundredths).
  1152.  
  1153.  
  1154.  
  1155. Procedures and Functions                                               42
  1156. Hours     returns the number of Hours since midnight in the format: hh
  1157.           (no leading zero).
  1158. Minutes   returns the number of minutes since midnight in the format: mmmm
  1159.           (no leading zeros).
  1160. Seconds   returns the number of seconds since midnight in the format:
  1161.           sssss (no leading zeros).
  1162. Elapsed   returns 'sssssssss.uuuuuu', the number of seconds (and hun-
  1163.           dredths) since the elapsed time clock was started or reset.  The
  1164.           number will have no leading zeros or blanks, and is not
  1165.           affected by the setting of NUMERIC DIGITS.
  1166. Reset     returns 'sssssssss.uuuuuu', the number of seconds (and hun-
  1167.           dredths) since the elapsed time clock was started or reset, and
  1168.           simultaneously resets the elapsed time clock to zero.  The num-
  1169.           ber will have no leading zeros or blanks, and is not affected
  1170.           by the setting of NUMERIC DIGITS.
  1171.  
  1172.     Examples:
  1173.  
  1174.     TIME('L')  == '16:54:22.123456'
  1175.     TIME()     == '16:54:22'
  1176.     TIME('H')  == '16'
  1177.     TIME('M')  == '1014'   /* 54 + 60*16 */
  1178.     TIME('S')  == '60862'  /* 22 + 60*(54+60*16) */
  1179.  
  1180.  
  1181. The elapsed time clock
  1182.  
  1183. The time function may be used for measuring real (elapsed) time intervals.
  1184. On the first call in a program to the TIME('E') or TIME('R'), the elapsed
  1185. time clock is started and either call would return 0.  From then on, calls
  1186. to TIME('E') or TIME('R') will return the elapsed time since that first
  1187. call or since the last call to TIME('R').
  1188.  
  1189.     Examples:
  1190.  
  1191.     TIME('E') ==  0           /* first call in program */`
  1192.     TIME('E') ==  1.120000    /* approx 1 second */
  1193.     TIME('R') ==  2.220000    /* approx 1 more second */
  1194.     TIME('R') ==  1.120000    /* approx 1 second since last time(r) */
  1195.  
  1196. The clock is saved across internal routine calls, which is to say that an
  1197. internal routine will inherit the time clock started by its caller,
  1198. but if it should reset the clock, then any timing being done by the caller
  1199. will not be affected.
  1200.  
  1201. Note: The first call to TIME in one expression causes a time stamp to be
  1202. made which is then used for all calls to this function in that expression.
  1203. Hence if multiple calls to any of the TIME functions are made in a single
  1204. expression, they are guaranteed to be consistent with each other.
  1205.  
  1206. ┌────────────────────────────────────────────────────────────────────────┐
  1207. │                         TRACE( [ setting ] )                           │
  1208. └────────────────────────────────────────────────────────────────────────┘
  1209.  
  1210. returns the trace setting currently in effect, and optionally alters the
  1211. trace setting.
  1212.  
  1213. If setting is supplied, it is used to select the trace setting.  The set-
  1214. ting must be a valid prefix("?") and/or one of the alphabetic character
  1215. settings (A,C,E,F,I,L,N or R) associated with the TRACE instruction.
  1216.  
  1217. ┌────────────────────────────────────────────────────────────────────────┐
  1218. │    TRANSLATE( string [ , [ tableo ] [ , [ tablei ] [ , pad ] ] ] )     │
  1219. └────────────────────────────────────────────────────────────────────────┘
  1220.  
  1221. Translates characters in string to other characters, or may be used to
  1222. reorder characters in a string.  The input translate table is tablei (the
  1223. default is XRANGE('00'x,'FFx)), and tableo is the output table.  If nei-
  1224. ther translate table is given, string is simply translated to upper case.
  1225. The output table defaults to the null string, and is padded with pad
  1226. characters or truncated as necessary.  The default pad is a blank.
  1227.  
  1228. The tables may be of any length; the first occurrence of a character in
  1229. the input table is the one that is used if there are any duplicates.  If a
  1230.  
  1231.  
  1232. Procedures and Functions                                               43
  1233. character in string does not appear in tablei then it will appear in the
  1234. result string unchanged.
  1235.  
  1236.     Examples:
  1237.  
  1238.     TRANSLATE('abcdef')                 == 'ABCDEF'
  1239.     TRANSLATE('abbc','&','b')           == 'a&&c'
  1240.     TRANSLATE('abcdef','12','ec')       == 'ab2d1f'
  1241.     TRANSLATE('abcdef','12','abcd','.') == '12..ef'
  1242.     TRANSLATE('4123','abcd','1234')     == 'dabc'
  1243.  
  1244. ┌────────────────────────────────────────────────────────────────────────┐
  1245. │                        TRUNC( number [ , n ] )                         │
  1246. └────────────────────────────────────────────────────────────────────────┘
  1247.  
  1248. returns the integer part of the number, and n decimal places (digits after
  1249. the decimal point).  n must be non-negative and defaults to zero.  The
  1250. number is truncated to n decimal places (or trailing zeros are added if
  1251. needed to make up the specified length).  If n is 0 (the default) than an
  1252. integer with no decimal point is returned.  The result will never be in
  1253. exponential form.
  1254.  
  1255.     Examples:
  1256.  
  1257.     TRUNC(12.3)           == 12
  1258.     TRUNC(127.09782,3)    == 127.097
  1259.     TRUNC(127.1,3)        == 127.100
  1260.     TRUNC(127,2)          == 127.00
  1261.  
  1262. Note:  The number will be rounded according to the current setting of NU-
  1263. MERIC DIGITS, if necessary, before being processed by the function.
  1264.  
  1265. ┌────────────────────────────────────────────────────────────────────────┐
  1266. │                             VALUE( name )                              │
  1267. └────────────────────────────────────────────────────────────────────────┘
  1268.  
  1269. returns the value of the symbol name.  As with symbols appearing normally
  1270. in REXXPC88 expressions, lower case characters in the name will be
  1271. translated to upper case and substitution in a compound name will occur
  1272. if possible.  name must be a valid REXXPC88 symbol, or an error results.
  1273.  
  1274. ┌────────────────────────────────────────────────────────────────────────┐
  1275. │        VERIFY( string , reference [ , [ option ] [ start ] ] )         │
  1276. └────────────────────────────────────────────────────────────────────────┘
  1277.  
  1278. verifies that the string is composed only of characters from reference,
  1279. by returning the position of the first character in string that is not
  1280. also in reference.  If all the characters were found in reference, 0 is
  1281. returned.
  1282.  
  1283. The option may be either 'Nomatch' (the default) or 'Match'.  Only the
  1284. first character of option is significant and it may be in upper case or
  1285. lower case, as usual.  If 'Match' is specified, the position of the first
  1286. character in string that is in reference is returned, or 0 if none of the
  1287. characters were found.
  1288.  
  1289. The default for start is 1, i.e., the search starts at the first character
  1290. of string.  This can be overridden by giving a different start point,
  1291. which must be positive.
  1292.  
  1293. If string is null, the function returns 0, regardless of the value of the
  1294. third argument (option).  Similiarly, if start is greater than
  1295. LENGTH(string), 0 is returned
  1296.  
  1297.     Examples:
  1298.  
  1299.     VERIFY('123','1234567890')           == 0
  1300.     VERIFY('1Z3','1234567890')           == 2
  1301.     VERIFY('AB4T','1234567890','M')      == 3
  1302.     VERIFY('1P3Q4','1234567890',,3)      == 4
  1303.     VERIFY('AB3CD5','1234567890','M',4)  == 6
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309. Procedures and Functions                                               44
  1310. ┌────────────────────────────────────────────────────────────────────────┐
  1311. │                          WORD( string , n )                            │
  1312. └────────────────────────────────────────────────────────────────────────┘
  1313.  
  1314. Returns the nth blank-delimited word in string.  n must be positive.  If
  1315. there are less than n words in string, then the null string is returned.
  1316. Exactly equivalent to SUBWORD(string,n,1).
  1317.  
  1318.     Examples:
  1319.  
  1320.     WORD('Now is the time',3) == 'the'
  1321.     WORD('Now is the time',5) == ''
  1322.  
  1323.  
  1324. ┌────────────────────────────────────────────────────────────────────────┐
  1325. │                        WORDINDEX( string , n )                         │
  1326. └────────────────────────────────────────────────────────────────────────┘
  1327.  
  1328. Returns  the  character  position  of  the nth blank-delimited word in
  1329. string.  n must be positive.  If there are not n words in string, then 0
  1330. is returned.
  1331.  
  1332.     Examples:
  1333.  
  1334.     WORDINDEX('Now is the time',3) == 8
  1335.     WORDINDEX('Now is the time',6) == 0
  1336.  
  1337.  
  1338. ┌────────────────────────────────────────────────────────────────────────┐
  1339. │                       WORDLENGTH( string , n )                         │
  1340. └────────────────────────────────────────────────────────────────────────┘
  1341.  
  1342. Returns the length of  the nth blank-delimited word in string.  n must be
  1343. positive.  If there are not n words in string, then 0 is returned.
  1344.  
  1345.     Examples:
  1346.  
  1347.     WORDLENGTH('Now is the time',2)     == 2
  1348.     WORDLENGTH('Now comes the time',2)  == 5
  1349.     WORDLENGTH('Now is the time',6)     == 0
  1350.  
  1351.  
  1352. ┌────────────────────────────────────────────────────────────────────────┐
  1353. │                WORDPOS( phrase , string [ , start ] )                  │
  1354. └────────────────────────────────────────────────────────────────────────┘
  1355.  
  1356. searches string for the first occurrence of the sequence of blank-
  1357. delimited words phrase, and returns the word number of the first word of
  1358. phrase in string. Multiple blanks between words in either phrase or string
  1359. are treated as a single blank for comparison, but otherwise the words
  1360. must match exactly.  Returns 0 if phrase is not found.
  1361.  
  1362. By default the search starts at the first word in string.  This may be
  1363. overridden by specifying start (which must be positive), the word at which
  1364. to start the search.
  1365.  
  1366. * Note:  The function FIND is replaced with this function.  See the differ-
  1367. * ences section for more info.
  1368.  
  1369.     Examples:
  1370.  
  1371.     WORDPOS('the','now is the time')         == 3
  1372.     WORDPOS('The','now is the time')         == 0
  1373.     WORDPOS('is the','now is the time')      == 2
  1374.     WORDPOS('is    the','now is the time')   == 2
  1375.     WORDPOS('is  time ','now is  the time')  == 0
  1376.     WORDPOS('be','To be or not to be')       == 2
  1377.     WORDPOS('be','To be or not to be',3')    == 6
  1378.  
  1379. ┌────────────────────────────────────────────────────────────────────────┐
  1380. │                            WORDS( string )                             │
  1381. └────────────────────────────────────────────────────────────────────────┘
  1382.  
  1383. Returns the number of blank-delimited words in string.
  1384.  
  1385.  
  1386. Procedures and Functions                                               45
  1387.     Examples:
  1388.  
  1389.     WORDS('Now is the time') == 4
  1390.     WORDS('  ')              == 0
  1391.  
  1392.  
  1393. ┌────────────────────────────────────────────────────────────────────────┐
  1394. │                          ASK( [ 'noecho' ] )                           │
  1395. └────────────────────────────────────────────────────────────────────────┘
  1396.  
  1397. Ask returns a line read from standard input.  As characters are typed by
  1398. the user, they are echoed unless the string "noecho" is supplied as an
  1399. argument to ask, in which case they are not echoed.  The backspace key
  1400. may be used to edit the input line.  Characters are read until the ENTER
  1401. key is typed.  The ENTER key is not included as part of the returned
  1402. string.  Example:
  1403.  
  1404.     /* prompt for a response            */
  1405.     say 'Enter your name'
  1406.     /* get it (echo the response)       */
  1407.     name = ask()
  1408.     /* prompt for another response      */
  1409.     say 'Enter your password'
  1410.     /* get it (don't echo the response) */
  1411.     pword = ask(noecho)
  1412.  
  1413. ┌────────────────────────────────────────────────────────────────────────┐
  1414. │                                 VER()                                  │
  1415. └────────────────────────────────────────────────────────────────────────┘
  1416.  
  1417. returns the current DOS version number in the format m.nn, where m is the
  1418. major version number and nn is the minor version number.
  1419.  
  1420.     Examples:
  1421.  
  1422.     VER()   == 2.00       /* for dos 2.0 */
  1423.     VER()   == 2.10       /* for dos 2.1 */
  1424.     VER()   == 3.00       /* for dos 3.0 */
  1425.     VER()   == 3.10       /* for dos 3.1 */
  1426.     VER()   == 3.20       /* for dos 3.2 */
  1427.  
  1428. Note: I intend to add another word identifying the language currently
  1429. active.
  1430.  
  1431. ┌────────────────────────────────────────────────────────────────────────┐
  1432. │                           GETENV( string )                             │
  1433. └────────────────────────────────────────────────────────────────────────┘
  1434.  
  1435. returns the contents of the environment variable string.  If string is not
  1436. found, the null string is returned.
  1437.  
  1438. The name of the environment variable string does NOT include the equal
  1439. ('=') sign.
  1440.  
  1441.     Examples:
  1442.  
  1443.     GETENV('PATH')     == 'C:\;'    /* perhaps */
  1444.     GETENV('xyz')      == ''        /* perhaps */
  1445.  
  1446. Note:
  1447.  
  1448.     The string may be in either upper or lower case.
  1449.  
  1450.     For PC/DOS this function searches the environment area of the master
  1451.     copy of COMMAND.COM or the process that this REXXPC88 program is
  1452.     running under.  If it is COMMAND.COM and the environment area moves
  1453.     from its default location (either resident version or standalone
  1454.     version) then changes to the environment will not be found until the
  1455.     next REXXPC88 program is run.
  1456.  
  1457. ┌────────────────────────────────────────────────────────────────────────┐
  1458. │                         EXTLOADED( funcname )                          │
  1459. └────────────────────────────────────────────────────────────────────────┘
  1460.  
  1461.  
  1462.  
  1463. Procedures and Functions                                               46
  1464. returns either "0" or "1" depending on whether the resident extension
  1465. named funcname answered the loaded call.
  1466.  
  1467. Note: This function uses the new AX=7 loaded function to determine the
  1468. value to be returned.  The extension must be coded to respond to the call
  1469. properly.
  1470.  
  1471.     Examples:
  1472.  
  1473.     EXTLOADED('HSAY')    == '0'   /* probably, rex2host function */
  1474.     EXTLOADED('DISPLAY') == '0'   /* for sure, rexxezvu function */
  1475.  
  1476. ┌────────────────────────────────────────────────────────────────────────┐
  1477. │    LISTFILE( [ filespec ] [ , [ attributes ] ] [ , [ option ] ] )      │
  1478. └────────────────────────────────────────────────────────────────────────┘
  1479.  
  1480. Listfile provides a file listing capability like that of the listfile
  1481. command on VM.
  1482.  
  1483. Filespec is the optional parameter that is the file name string to search
  1484. for.  This spec may include the global file name characters * and ?.  If
  1485. not specified the filespec defaults to "*.*".
  1486.  
  1487. Attributes is the optional decimal numeric value of the file attributes
  1488. to search for.
  1489.  
  1490. If attribute is a positive number, the search will take place according
  1491. to the standard DOS rules concerning inclusive and exclusive searches
  1492. (i.e., you will get files on all searches, even if you ask for directories
  1493. only).
  1494.  
  1495. If attribute is a negative number, the search will return ONLY those files
  1496. which match exactly the option specified.  The absolute value of attribute
  1497. is used in all cases.
  1498.  
  1499. Note: See the DOS Technical Reference manual for a description of the
  1500. values for this field.  If not specified the attribute defaults to 55, all
  1501. attributes.
  1502.  
  1503. If option is supplied as the third argument, it must evaluate to one of
  1504. the following strings:
  1505.  
  1506. FIFO      The result of the listfile command is to be placed on the data
  1507.           queue in First-in, First-out order.
  1508. LIFO      The result of the listfile command is to be placed on the data
  1509.           queue in Last-in, First-out order.
  1510. any other The result of the listfile command is to be displayed on the
  1511.           users console.
  1512.  
  1513. The data returned by listfile consists of the following info:
  1514.  
  1515. fn        File name including dot between filename and extension with NO
  1516.           imbedded spaces.
  1517. fsize     File size in bytes, directories are 0.
  1518. fattr     File attributes in decimal.  See the DOS Technical Reference
  1519.           under file attributes for the values.
  1520. wdate     Last file write date
  1521. ftime     Last file write time
  1522. [<DIR>]   If the file is a directory this string will be the last field
  1523.  
  1524.           This allows a quich check without having to know the attribute
  1525.           of a directory entry (16).
  1526. [<VOL>]   If the file is a volume label this string will be the last field
  1527.  
  1528.           This allows a quick check without having to know the attribute
  1529.           of a volume label (8).
  1530.  
  1531. * ┌────────────────────────────────────────────────────────────────────────┐
  1532. * │                               REXXRES()                              │
  1533. * └────────────────────────────────────────────────────────────────────────┘
  1534.  
  1535. *  This  function  will  provide  an  indicator for whether the RESIDENT or
  1536. *  STANDALONE version is running the REXXIBM program.  The result of the
  1537. *  function is '1' if resident version, or '0' if standalone version.
  1538.  
  1539.  
  1540. Procedures and Functions                                               47
  1541. *   Examples:
  1542. *
  1543. *   REXXRES()   == '0'  /* if STANDALONE version executing */
  1544. *   REXXRES()   == '1'  /* if RESIDENT version executing */
  1545. *
  1546.  
  1547.  
  1548.  
  1549. File management routines
  1550.  
  1551.  
  1552.  
  1553. ┌────────────────────────────────────────────────────────────────────────┐
  1554. │                     DIRECTORY( [ newdirectory ] )                      │
  1555. └────────────────────────────────────────────────────────────────────────┘
  1556.  
  1557. This function returns the "current working directory", first changing it
  1558. to newdirectory if an argument is supplied and the new directory exists.
  1559.  
  1560. Under MSDOS, directory() returns a drive letter prefix as the first two
  1561. characters of the directory name.  Specifying a drive letter prefix as
  1562. part of the newdirectory string causes that drive to become the "current
  1563. drive".  If a directory is specified, then in addition that directory
  1564. becomes the "current directory".  If no drive letter is specified, then
  1565. the "current drive" remains unchanged.
  1566.  
  1567. The following program fragment saves the current directory,  switches to
  1568. a new directory, performs an operation there, and then returns to the
  1569. former directory.
  1570.  
  1571.     /* get current directory */
  1572.   curdir = directory()
  1573.   /* go play a game */
  1574.   newdir = directory("d:/usr/games")
  1575.   if newdir = "d:/usr/games" then
  1576.      do
  1577.      fortune  /* tell a fortune */
  1578.   /* return to former directory */
  1579.      call directory curdir
  1580.      end
  1581.   else
  1582.      say 'Can''t find /usr/games'
  1583.  
  1584. ┌────────────────────────────────────────────────────────────────────────┐
  1585. │                    READ( filename [ , position ] )                     │
  1586. └────────────────────────────────────────────────────────────────────────┘
  1587.  
  1588. Read returns one line from the file named in its first argument, starting
  1589. at the current read/write position (which is the beginning of the  file
  1590. if the file has never been read or written).  The read/write position is
  1591. advanced by the size of the line read.  A carriage return, followed by a
  1592. linefeed is expected to terminate the line, but it and the linefeed is
  1593. thrown away and not included in the returned string.
  1594.  
  1595. If the end of file is encountered, ''  (an empty string) is returned.
  1596.  
  1597. A line consisting of 0 characters followed by a carriage return (and
  1598. perhaps a linefeed) is returned as ' '  (a string containing a single
  1599. blank) so that it can't be misinterpreted as indicating the end of the
  1600. file.  Example:
  1601.  
  1602.   /* display a file */
  1603.   say 'Enter filename'    /* ask user for a name */
  1604.   fname = ask ()            /* get his response  */
  1605.   do forever
  1606.      fline = read(fname)    /* next line of file */
  1607.      say fline              /* display it        */
  1608.      if fline == '' then    /* is it empty?      */
  1609.         do                  /* yes... we're done */
  1610.         say 'END-OF-FILE'
  1611.         return
  1612.         end
  1613.   end
  1614.  
  1615.  
  1616.  
  1617. Procedures and Functions                                               48
  1618.  
  1619. there is a limit on the length of the longest line that can be read (See
  1620. "Appendix G. Bugs and Limitations" on page 73).
  1621.  
  1622. ┌────────────────────────────────────────────────────────────────────────┐
  1623. │                    SEEK( filename [ , position ] )                     │
  1624. └────────────────────────────────────────────────────────────────────────┘
  1625.  
  1626. Seek may be used to find out, or to set, the byte offset within filename
  1627. at which subsequent reading or writing will take place.  If the second
  1628. argument is omitted, seek returns the current read/write position.  If
  1629. the second argument is supplied, REXXPC88 will reset its read/write po-
  1630. sition to that offset within the file.  The second argument must be a
  1631. number and must be positive or zero.  Examples:
  1632.  
  1633.   /* point read/write position to the first
  1634.    * character of a file
  1635.    */
  1636.   myfile = 'd:/tmp/junk.jnk'
  1637.   call seek myfile, 0
  1638.  
  1639.   /* find out current read/write position */
  1640.   curpos = seek(myfile)
  1641.  
  1642.   /* point read/write position to the EOF character
  1643.    * at the end of a standard DOS text file, so
  1644.    * subsequent write()'s will append to the file
  1645.    */
  1646.   call seek myfile, size(myfile) - 1
  1647.  
  1648. ┌────────────────────────────────────────────────────────────────────────┐
  1649. │                           SIZE( FILENAME )                             │
  1650. └────────────────────────────────────────────────────────────────────────┘
  1651.  
  1652. If filename exists, its size (in bytes) is returned.  Otherwise '' (an
  1653. empty string) is returned.
  1654.  
  1655. ┌────────────────────────────────────────────────────────────────────────┐
  1656. │                WRITE( filename , string [ , option ] )                 │
  1657. └────────────────────────────────────────────────────────────────────────┘
  1658.  
  1659. Write writes the string supplied as its second argument to the file named
  1660. by its first argument.  The string is written at the current read/write
  1661. position (which is the beginning of the file if the file has never been
  1662. read or written).  The read/write position is advanced by the length of
  1663. the string written.
  1664.  
  1665. Write returns '' (an empty string) if the write failed to a disk-full
  1666. condition or a read-only file.  Otherwise it returns the string that was
  1667. written.
  1668.  
  1669. If option is supplied as the third argument, it must evaluate to one of
  1670. the following strings:
  1671.  
  1672. eol       a carriage return and line feed ('0D'x and '0A'x, respectively)
  1673.           are written to the file following the string.  The read/write
  1674.           position is advanced by 2, in addition to the length of the
  1675.           string.
  1676. eof       an end-of-file mark ('1A'x) is written to the file following
  1677.           the string.  The read/write position is advanced by 1, in ad-
  1678.           dition to the length of the string.
  1679. a number  the number is used as a screen writing attribute (this applies
  1680.           only to the special file named "screen"; see "Appendix B. Spe-
  1681.           cial files" on page 56).
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694. Procedures and Functions                                               49
  1695. Example 1:
  1696.  
  1697.   /* create a new file and write 2 lines to it */
  1698.  
  1699.   myfile = 'd:/tmp/junk.jnk'
  1700.   if size(myfile) <> '' then  /* file exists... */
  1701.      erase myfile             /* ...erase it    */
  1702.   call write myfile, 'Hello world', eol /*line 1*/
  1703.   call write myfile, 'Whats ' /*line 2, part 1  */
  1704.   call write myfile, 'new', eol /*line 2, part 2*/
  1705.   call write myfile, '', eof /* empty line + EOF*/
  1706.  
  1707.   /* the file now contains the following data:
  1708.    * Hello world<CR><LF>Whats new<CR><LF><EOF>
  1709.    */
  1710.  
  1711.   /* read back the first line and display it */
  1712.  
  1713.   call seek myfile, 0    /* point to the first line */
  1714.   say read(myfile)       /* read and display        */
  1715.  
  1716.   /* change the second line */
  1717.  
  1718.   call seek myfile, 19      /* point to 'new' */
  1719.   /* change 'new' to 'old' */
  1720.   call write myfile, 'old'
  1721.  
  1722.   /* re-display second line */
  1723.  
  1724.   call seek myfile, 13    /* point to 2nd line */
  1725.   say read(myfile)        /* read and display  */
  1726.  
  1727.  
  1728. Example 2:
  1729.  
  1730.   /* write with error detection */
  1731.  
  1732.   if write(myfile, 'abc', eol) == '' then
  1733.      do
  1734.      say 'Write failed'
  1735.      exit
  1736.      end
  1737.  
  1738. ┌────────────────────────────────────────────────────────────────────────┐
  1739. │                          FINISH( filename )                            │
  1740. └────────────────────────────────────────────────────────────────────────┘
  1741.  
  1742. Finish forces any pending output to be written to  the named file and
  1743. then frees REXXPC88's internal file tables for future use.  The finish
  1744. function need only be called explicitly if you will be manipulating a
  1745. large number of files (the exact number depends on how REXXPC88 was in-
  1746. voked:  see "Executing A Rexx Program") with the read, write, or seek
  1747. functions.  REXXPC88  will  automatically finish  all  active  files for
  1748. you before terminating your program.  Example:
  1749.  
  1750.   /* Write 20 files */
  1751.   do i = 1 to 20
  1752.      /* write next file... */
  1753.      say write(testfile.i, 'This is' testfile.i, eol)
  1754.      /* we're done with this file for now... */
  1755.      call finish testfile.i
  1756.      end
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771. Procedures and Functions                                               50
  1772.